Windows Azure Storage : Queue Operations

Table 2 lists some of the important characteristics of the queue operations listed in Table 1.

Table 2 lists the HTTP verb, cloud URI, development storage URI, HTTP version, and access control for the queues. The <account name> is the storage account name in the cloud, and the <devstorageaccount> is the development storage account. Observe that unlike blob containers, all the operations can be called only with the account owner privileges.

The following sections discuss some of the operations from Table 5-7 in detail. Even though the operations are different, the programming concepts behind them are similar. To keep the book at a conceptual level, I discuss just the Create Queue and Set Queue Metadata operations. By studying these operations in detail, you can understand the programming concepts behind all the queue operations. The Windows Azure Storage Operations application included with this chapter's source code contains an implementation of all the queue operations.

1. Create Queue

The Create Queue operation creates a queue in a storage account. The URI for the Create Queue operation is of the format account name>.queue.core.windows.net/<queue name>. You can think of Queue as a message queuing system in the cloud. For example, if you want to send and receive messages across diverse applications in different domains, Windows Azure Queue may fit your requirement. Because of its standard REST interface and Internet scale, you can send and receive queue messages anywhere, anytime, and in any programming language that supports Internet programming. The Create Queue REST request looks like Listing 5-8.

Example 1. Create Queue REST Request

PUT /myfirstazurequeue?timeout=30 HTTP/1.1
x-ms-date: Wed, 17 Jun 2009 03:16:12 GMT
Authorization: SharedKey proazurestorage:a0EQSlfMdXfFrP/wwdfCUVqMYiv4PjXesF0Jp4d71DA=
Host: proazurestorage.queue.core.windows.net
Content-Length: 0

					  

Listing 1 shows the request for creating a queue named myfirstazurequeue. The PUT HTTP verb instructs the Queue service to create a queue. There is no metadata information for the queue, so the queue is created without any metadata. You can add x-ms-meta-[name]:[value] to the header to create metadata values. For the Create Queue operation, the Queue service responds with a status code of HTTP/1.1 201 Created, or HTTP/1.1 409 Conflict if a queue with the same name already exists. The Create Queue response is shown in Listing 2.

Example 2. Create Queue REST Response

HTTP/1.1 201 Created
Server: Queue Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 8b4d45c8-2b5d-46b8-8e14-90b0d902db80
Date: Wed, 17 Jun 2009 03:17:57 GMT
Content-Length: 0

In Listing 2, the first line represents the status code of the operation. The x-ms-request-id represents a unique request identifier that can be used for debugging or tracing.

Figure 1 shows the working of the Create Queue operation in the Windows Azure Storage Operations application.

Figure 1. Create Queue from Windows Azure Storage Operations.exe

As shown in Figure 5-8, to create a queue, you need to do the following:

The WindowsAzureStorageHelper class in the ProAzureCommonLib contains a helper function called CreateQueue, as shown in Listing 3.

Example 3. Create Queue Method in the WindowsAzureStorageHelper Class

public bool CreateQueue(string queueName, out bool alreadyExists)
{
alreadyExists = false;
MessageQueue q = QueueStorageType.GetQueue(queueName);

return q.CreateQueue(out alreadyExists);
}

As shown in Listing 3, the CreateQueue() method calls the GetQueue() method to get a reference to the MessageQueue object. The MessageQueue object is a local instance of the Queue object. This instance doesn't create a queue when you instantiate it. To create a queue, you have to call the CreateQueue() method on the MessageQueue object. The MessageQueue object is used by the StorageClient to create accurate URI and metadata headers and send them to the Queue service. Figure 2 illustrates the sequence of method calls across different objects and assemblies for the Create Queue operation.

Figure 2. Create Queue sequence diagram

As shown in Figure 2, the Windows Azure Storage Operations application calls the CreateQueue() method on the WindowsStorageHelper object in the ProAzureCommonLib.dll. The WindowsStorageHelper object calls the GetQueue() method on the QueueStorage object to get an instance of the MessageQueue object. The WindowsStorageHelper object then calls the CreateQueue() method on the MessageQueue object. The CreateQueue() method creates the REST message and sends it synchronously to the Windows Azure Queue service to create the queue. It uses the System.Net.HttpWebRequest to send the REST message over HTTP. Upon success or failure of the operation, the Windows Azure Queue service returns an HTTP status code: HTTP/1.1 201 for success or HTTP/1.1 409 for conflict or failure. The CreateQueue() method translates the HTTP status code into true for success and false for failure or conflict. The Boolean value is passed all the way to the Windows Azure Storage Operations application as a return parameter of the CreateQueue() method.

2. Set Queue Metadata

Queues can contain name-value pairs of metadata values. You can store values like the time of creation, creator, last modified by user, and so on in the metadata fields of a container. The size of the metadata can be 8KB per queue. The Set Queue Metadata operation sets the metadata of a queue independently. The URI for the Set Queue Metadata operation is of the format account name>.queue.core.windows.net/<queue name>?comp=metadata. The Set Queue Metadata REST request looks like Listing 4.

Example 4. Set Queue Metadata REST Request

PUT /myfirstazurequeue?comp=metadata&timeout=30 HTTP/1.1
x-ms-date: Wed, 17 Jun 2009 04:33:45 GMT
x-ms-meta-createdBy: tejaswi
x-ms-meta-creationDate: 6/16/2009
Authorization: SharedKey proazurestorage:spPPnadPYnH6AJguuYT9wP1GLXmCjn0I1S6W2+hzyMc=
Host: proazurestorage.queue.core.windows.net
Content-Length: 0

					  

In Listing 5, the HTTP verb used is PUT, and the URI parameter is ?comp=metadata. This parameter instructs the Queue service to set the queue metadata instead of creating the queue. The Create Queue operation doesn't have this parameter. The x-ms-meta.[name]:[value] entries represent the metadata name-value pairs you want to set on the queue.

Figure 3 illustrates how to execute the Set Queue Metadata operation in Windows Azure Storage Operations application.

Figure 3. Set Queue Metadata in the Windows Azure Storage Operations application

As shown in Figure 3, to execute the Set Queue Metadata operation, you do the following:

The WindowsAzureStorageHelper class in the ProAzureCommonLib contains a helper function called SetQueueProperties(), as shown in Listing 5.

Example 5. SetQueueProperties Method in the WindowsAzureStorageHelper Class

public bool SetQueueProperties(string queueName, QueueProperties queueProps)
{
MessageQueue q = QueueStorageType.GetQueue(queueName);

return q.SetProperties(queueProps);
}

					  

In Listing 5, the SetQueueProperties() method accepts the name of the queue and a QueueProperties object populated with metadata name-value pairs. The QueueProperties class has a property Metadata of type System.Collections.Specialized.NameValueCollection, which represents the metadata name-value pairs. The queue name is used to create a local instance of the MessageQueue object. The code then calls the SetProperties() method on the MessageQueue object to set the metadata values for the queue. If the metadata is set successfully, a Boolean value of true is returned back to the caller; otherwise, a false value is returned. Figure 4 illustrates the sequence of method calls across different objects and assemblies for the Set Queue Metadata operation.

Figure 4. Set Queue Metadata sequence diagram

As shown in Figure 4, the Windows Azure Storage Operations application calls the SetQueueProperties() method on the WindowsStorageHelper object in the ProAzureCommonLib.dll. The WindowsStorageHelper object calls the GetQueue() method on the QueueStorage object to get an instance of the MessageQueue object. The WindowsStorageHelper object then calls the SetProperties() method on the MessageQueue object. The SetProperties() method creates the REST message and sends it synchronously to the Windows Azure Queue service to set the queue metadata values. It uses the System.Net.HttpWebRequest to send the REST message over HTTP. Upon success or failure of the operation, the Windows Azure Queue service returns an HTTP status code: HTTP/1.1 200 for success or HTTP/1.1 204 (No content). The SetProperties() method translates the HTTP status code into true for success and false for failure. The Boolean value is passed all the way to the Windows Azure Storage Operations application as a return parameter of the SetQueueProperties() method.